home *** CD-ROM | disk | FTP | other *** search
/ Aminet 45 / Aminet 45 (2001)(GTI - Schatztruhe)[!][Oct 2001].iso / Aminet / game / role / ldmud-3.2-bin.lha / mud / doc / efun / debug_info < prev    next >
Text File  |  2001-03-21  |  14KB  |  358 lines
  1. SYNOPSIS
  2.         #include <debug_info.h>
  3.  
  4.         mixed debug_info(int flag)
  5.         mixed debug_info(int flag, mixed arg)
  6.         mixed debug_info(int flag, mixed arg2, mixed arg3)
  7.  
  8. DESCRIPTION
  9.         Gather some driver internal debug information according
  10.         to the setting of flag:
  11.  
  12.         DINFO_OBJECT (0): Information like heart_beat, enable_commands
  13.             etc. of the specified object will be printed, and 0 returned.
  14.  
  15.         DINFO_MEMORY (1): Memory usage information like how many strings,
  16.             variables, inherited files, object size etc. will be printed
  17.             about the specified object, and 0 returned.
  18.  
  19.         DINFO_OBJLIST (2): Objects from the global object list are
  20.             returned.  If the optional second arg is omitted, the first
  21.             element (numbered 0) is returned. If the second arg is a
  22.             number n, the n'th element of the object list returned. If the
  23.             second arg is an object, it's successor in the object list is
  24.             returned.
  25.  
  26.         DINFO_MALLOC (3): Equivalent to typing ``malloc'' at the command
  27.             line. No second arg must be given. Returns 0.
  28.  
  29.         DINFO_STATUS (4): Collect the status information of the driver.
  30.             The optional second arg can be 0, "tables", "swap", "malloc"
  31.             or any other argument accepted by the actual driver.
  32.             The result is a printable string with the status information,
  33.             or 0 if an invalid argument was given.
  34.  
  35.         DINFO_DUMP (5): Dump the information specified by <arg2> into the
  36.             filename specified by <arg3>. If <arg3> is omitted, a default
  37.             file name is used. The function calls master->valid_write() to
  38.             check that it can write the files. The file in question is
  39.             always written anew.
  40.  
  41.             Result is 1 on success, or 0 if an error occured.
  42.  
  43.             <arg2> == "objects": dump information about all objects.
  44.               Default filename is '/OBJ_DUMP', the valid_write() will read
  45.               'objdump' for the function.
  46.             <arg2> == "opcodes": dump usage information about the opcodes.
  47.               Default filename is '/OPC_DUMP', the valid_write() will read
  48.               'opcdump' for the function.
  49.  
  50.         DINFO_DATA (6): Return raw information about an aspect of
  51.             the driver specified by <arg2>. The result of the function
  52.             is an array with the information, or 0 for unsupported values
  53.             of <arg2>.
  54.             
  55.             If <arg3> is given and in the range of array indices
  56.             for the given <arg2>, the result will be just the indexed array
  57.             entry, but not the full array.
  58.  
  59.             Allowed values for <arg2> are: DID_STATUS, DID_SWAP, DID_MALLOC.
  60.  
  61.             <arg2> == DID_STATUS (0): Returns the "status" and "status tables"
  62.             information. Following indices are defined:
  63.  
  64.               int DID_ST_ACTIONS
  65.               int DID_ST_ACTIONS_SIZE
  66.                   Number and size of allocated actions.
  67.  
  68.               int DID_ST_SHADOWS
  69.               int DID_ST_SHADOWS_SIZE
  70.                   Number and size of allocated shadows.
  71.  
  72.               int DID_ST_OBJECTS
  73.               int DID_ST_OBJECTS_SIZE
  74.                   Number and size of swapped-in objects.
  75.  
  76.               int DID_ST_OBJECTS_SWAPPED
  77.               int DID_ST_OBJECTS_SWAP_SIZE
  78.                   Number and size of swapped-out object variable blocks.
  79.  
  80.               int DID_ST_OBJECTS_LIST
  81.                   Number of objects in the object list.
  82.  
  83.               int DID_ST_OBJECTS_PROCESSED
  84.                   Number of listed objects processed in the last backend
  85.                   cycle.
  86.  
  87.               float DID_ST_OBJECTS_AVG_PROC
  88.                   Average number of objects processed each cycle, expressed
  89.                   as percentage (0..1.0).
  90.  
  91.               int DID_ST_OTABLE
  92.                   Number of objects listed in the object table.
  93.  
  94.               int DID_ST_OTABLE_SLOTS
  95.                   Number of hash slots provided by the object table.
  96.  
  97.               int DID_ST_OTABLE_SIZE
  98.                   Size occupied by the object table.
  99.  
  100.               int DID_ST_HBEAT_OBJS
  101.                   Number of objects with a heartbeat.
  102.  
  103.               int DID_ST_HBEAT_CALLS
  104.                   Number of heart_beats executed so far.
  105.  
  106.               int DID_ST_HBEAT_CALLS_TOTAL
  107.                   Number of heart_beats calls so far. The difference to
  108.                   ST_HBEAT_CALLS is that the latter only counts heart beat
  109.                   calls during which at least one heart beat was actually
  110.                   executed.
  111.  
  112.               int DID_ST_HBEAT_SLOTS
  113.               int DID_ST_HBEAT_SIZE
  114.                   Number of allocated entries in the heart_beat table
  115.                   and its size.
  116.  
  117.               int DID_ST_HBEAT_PROCESSED
  118.                   Number of heart_beats called in the last backend cycle.
  119.  
  120.               float DID_ST_HBEAT_AVG_PROC
  121.                   Average number of heart_beats called each cycle, expressed
  122.                   as fraction (0..1.0).
  123.  
  124.               int DID_ST_CALLOUTS
  125.                   Number of pending call_outs.
  126.  
  127.               int DID_ST_CALLOUT_SLOTS
  128.               int DID_ST_CALLOUT_SIZE
  129.                   Number of allocated entries in the call_out table
  130.                   and its size.
  131.  
  132.               int DID_ST_ARRAYS
  133.               int DID_ST_ARRAYS_SIZE
  134.                   Number and size of all arrays.
  135.  
  136.               int DID_ST_MAPPINGS
  137.               int DID_ST_MAPPINGS_SIZE
  138.                   Number and size of all mappings.
  139.  
  140.               int DID_ST_PROGS
  141.               int DID_ST_PROGS_SIZE
  142.                   Number and size of all programs.
  143.  
  144.               int DID_ST_PROGS_SWAPPED
  145.               int DID_ST_PROGS_SWAP_SIZE
  146.                   Number and size of swapped-out programs.
  147.  
  148.               int DID_ST_USER_RESERVE
  149.               int DID_ST_MASTER_RESERVE     
  150.               int DID_ST_SYSTEM_RESERVE
  151.                   Current sizes of the three memory reserves.
  152.  
  153.               int DID_ST_ADD_MESSAGE
  154.               int DID_ST_PACKETS
  155.               int DID_ST_PACKET_SIZE
  156.                   Number of calls to add_message(), number and total size
  157.                   of sent packets.
  158.                   If the driver is not compiled with COMM_STAT, all three
  159.                   values are returned as -1.
  160.  
  161.               int DID_ST_APPLY
  162.               int DID_ST_APPLY_HITS
  163.                   Number of calls to apply_low(), and how many of these
  164.                   were cache hits.
  165.                   If the driver is not compiled with APPLY_CACHE_STAT, all two
  166.                   values are returned as -1.
  167.  
  168.               int DID_ST_STRINGS
  169.               int DID_ST_STRING_SIZE
  170.                   Number of distinct strings in the string table, and
  171.                   their size.
  172.  
  173.               int DID_ST_STR_TABLE_SIZE
  174.                   Size of the string table.
  175.  
  176.               int DID_ST_STR_REQ
  177.               int DID_ST_STR_REQ_SIZE
  178.                   Total number of string allocations, and their size.
  179.  
  180.               int DID_ST_STR_SEARCHES
  181.               int DID_ST_STR_SEARCH_LEN
  182.                   Number of searches in the string table, and the
  183.                   accumulated search length.
  184.  
  185.               int DID_ST_RX_CACHED
  186.                   Number of regular expressions cached.
  187.  
  188.               int DID_ST_RX_TABLE
  189.               int DID_ST_RX_TABLE_SIZE
  190.                   Number of slots in the regexp cache table, and size of the
  191.                   memory currently held by it and the cached expressions.
  192.  
  193.               int DID_ST_RX_REQUESTS
  194.                   Number of requests for new regexps.
  195.  
  196.               int DID_ST_RX_REQ_FOUND
  197.                   Number of requested regexps found in the table.
  198.  
  199.               int DID_ST_RX_REQ_COLL
  200.                   Number of requested new regexps which collided with
  201.                   a cached one.
  202.  
  203.             <arg2> == DID_SWAP (1): Returns the "status swap" information:
  204.  
  205.                int DID_SW_PROGS
  206.                int DID_SW_PROG_SIZE
  207.                    Number and size of swapped-out program blocks.
  208.  
  209.                int DID_SW_PROG_UNSWAPPED
  210.                int DID_SW_PROG_U_SIZE
  211.                    Number and size of unswapped program blocks.
  212.  
  213.                int DID_SW_VARS
  214.                int DID_SW_VAR_SIZE
  215.                    Number and size of swapped-out variable blocks.
  216.  
  217.                int DID_SW_FREE
  218.                int DID_SW_FREE_SIZE
  219.                    Number and size of free blocks in the swap file.
  220.  
  221.                int DID_SW_FILE_SIZE
  222.                    Size of the swap file.
  223.  
  224.                int DID_SW_REUSED
  225.                    Total reused space in the swap file.
  226.  
  227.                int DID_SW_SEARCHES
  228.                int DID_SW_SEARCH_LEN
  229.                    Number and total length of searches for block to reuse
  230.                    in the swap file.
  231.  
  232.                int DID_SW_F_SEARCHES
  233.                int DID_SW_F_SEARCH_LEN
  234.                    Number and total length of searches for a block to free.
  235.  
  236.                int DID_SW_COMPACT
  237.                    TRUE if the swapper is running in compact mode.
  238.  
  239.                int DID_SW_RECYCLE_FREE
  240.                    TRUE if the swapper is currently recycling free block.
  241.  
  242.  
  243.             <arg2> == DID_MEMORY (2): Returns the "status malloc" information:
  244.  
  245.                string DID_MEM_NAME
  246.                    The name of the allocator: "sysmalloc" or "smalloc".
  247.  
  248.                int DID_MEM_SBRK
  249.                int DID_MEM_SBKR_SIZE
  250.                    Number and size of memory blocks requested from the
  251.                    operating system (smalloc only).
  252.  
  253.                int DID_MEM_LARGE
  254.                int DID_MEM_LARGE_SIZE
  255.                int DID_MEM_LFREE
  256.                int DID_MEM_LFREE_SIZE
  257.                    Number and size of large allocated resp. free blocks.
  258.                    (smalloc only)
  259.  
  260.                int DID_MEM_LWASTED
  261.                int DID_MEM_LWASTED_SIZE
  262.                    Number and size of unusable large memory fragments.
  263.                    (smalloc only).
  264.  
  265.                int DID_MEM_CHUNK
  266.                int DID_MEM_CHUNK_SIZE
  267.                    Number and size of small chunk blocks (smalloc only).
  268.  
  269.                int DID_MEM_UNUSED
  270.                    Unused space in the current small chunk block
  271.                    (smalloc only).
  272.  
  273.                int DID_MEM_SMALL
  274.                int DID_MEM_SMALL_SIZE
  275.                int DID_MEM_SFREE
  276.                int DID_MEM_SFREE_SIZE
  277.                    Number and size of small allocated resp. free blocks
  278.                    (smalloc only).
  279.  
  280.                int DID_MEM_SWASTED
  281.                int DID_MEM_SWASTED_SIZE
  282.                    Number and size of unusably small memory fragments.
  283.                    (smalloc only).
  284.  
  285.                int DID_MEM_MINC_CALLS
  286.                int DID_MEM_MINC_SUCCESS
  287.                int DID_MEM_MINC_SIZE
  288.                    Number of calls to malloc_increment(), the number
  289.                    of successes and the size of memory allocated this
  290.                    way (smalloc only).
  291.  
  292.                int DID_MEM_PERM
  293.                int DID_MEM_PERM_SIZE
  294.                    Number and size of permanent (non-GCable) allocations
  295.                    (smalloc only).
  296.  
  297.                int DID_MEM_CLIB
  298.                int DID_MEM_CLIB_SIZE
  299.                    Number and size of allocations done through the
  300.                    clib functions (smalloc only with SBRK_OK).
  301.  
  302.  
  303.         DINFO_TRACE (7): Return the call stack 'trace' information as specified
  304.             by <arg2>. The result of the function is either an array (format
  305.             explained below), or a printable string. Omitting <arg2> defaults
  306.             to DIT_CURRENT.
  307.  
  308.             <arg2> == DIT_CURRENT (0) or == DIT_ERROR (1): Return the
  309.                information in array form. For DIT_CURRENT, the current call
  310.                trace is returned, for DIT_ERROR the trace of the last 
  311.                uncaught error.
  312.  
  313.                If the array has more than one entries, the first entry is 0 or
  314.                the name of the object with the heartbeat which started the
  315.                current thread; all following entries describe the call stack
  316.                starting with the topmost function called.
  317.  
  318.                All call entries are arrays themselves with the following
  319.                elements:
  320.  
  321.                int[TRACE_TYPE]: The type of the call frame:
  322.                    TRACE_TYPE_SYMBOL (0): a function symbol (shouldn't happen).
  323.                    TRACE_TYPE_SEFUN  (1): a simul-efun.
  324.                    TRACE_TYPE_EFUN   (2): an efun closure.
  325.                    TRACE_TYPE_LAMBDA (3): a lambda closure.
  326.                    TRACE_TYPE_LFUN   (4): a normal lfun.
  327.  
  328.                mixed[TRACE_NAME]: The 'name' of the called frame:
  329.                    _TYPE_EFUN:   either the name of the efun, or the code of
  330.                                  the instruction for operator closures
  331.                    _TYPE_LAMBDA: the numeric lambda identifier.
  332.                    _TYPE_LFUN:   the name of the lfun.
  333.  
  334.                string[TRACE_PROGRAM]: The (file)name of the program holding the
  335.                    code.
  336.                string[TRACE_OBJECT]:  The name of the object for which the code
  337.                                       was executed.
  338.                int[TRACE_LOC]:
  339.                    _TYPE_LAMBDA: current program offset from the start of the
  340.                                  closure code.
  341.                    _TYPE_LFUN:   the line number.
  342.  
  343.             <arg2> == DIT_STR_CURRENT (2): Return the information about the
  344.                current call trace as printable string.
  345.  
  346. HISTORY
  347.         Since 3.2.7, DINFO_STATUS returns the status information instead
  348.           of printing it.
  349.         DINFO_DUMP introduced with 3.2.7.
  350.         LDMud 3.2.8 added the data size of the object to the result of
  351.           DINFO_MEMORY; the DINFO_DATA request; the DID_MEM_WASTED* stats.
  352.         LDMud 3.2.9 added DINFO_TRACE; the indexing feature for DINFO_DATA,
  353.           the DID_MEM_CLIB* and DID_MEM_PERM* stats,
  354.           and DID_ST_HBEAT_CALLS_TOTAL.
  355.  
  356. SEE ALSO
  357.         trace(E), traceprefix(E), malloc(D), status(D), dumpallobj(D)
  358.